DirectSound for QB
==================
Lost socK software

FINAL VERSION 1.00 revision 2
This revision adds internal support for starting and terminating the slave...you never have to worry about starting the slave yourself anymore! Also, there is a compiled version of DEMOCODE now, so you don't even have to have QB to see DS4QB in action.

Hello?! DirectSound for QB? What a stupid concept! Or, is it? Let's all face it: Win32 features some powerful sound applications. Wouldn't it be nice to take advantage of them for your QB projects? With very few useful sound libraries for QB, this seems a logical choice. The first time I ever saw a QB program take advantage of the Windows sound resources was Master Creating's "Shadow Of Power". Nobody outside of their group knows how it was done (many have their theories). Thanks to the Bass sound library, some assistance from Toshi Horie and QbProgger (and a few others listed below), and countless hours of slaving over interrupt 2Fh, now anyone can use the Bass Dynamic Link Library in their QB program.

What does Bass.dll allow you to do?

-Play all major music module formats (MOD/S3M/XM/IT, plus MO3)
-Play MPEG-Layer 3 streams (MP3) or WAV streams
-Play WAV samples as sound effects
-Play CD Audio

Bass.dll can do so much more, but I've yet to add more capability to DS4QB. I will in a later release, but this release is intended to be the basic version, with all major functions completed.

"What?! MP3s in QB???" Yep...kinda. "How in the hell did you do that?!" Read on...

DirectSound for QB uses the Windows clipboard through the WinOldAp extension to communicate with a VB5-based controller. The controller is run, which starts the program you'll be using the services with. Without this controller running, the sound services will not be available. This document covers all the functions of DS4QB, so read up here, or view the example source that comes with this package. You will, of course, need to load QB with the default library loaded. DS4QB.BI must be '$INCLUDEd to access the routines in the library. It contains procedure declarations and all the globals that the library requires. The BI file also contains both interrupt headers and some useful constants.

DS4QB obviously requires DirectX to be installed on your computer. 99 times out of 100 this isn't a problem. If DX isn't on your system, let me schmacketh thee! err...point thee in the right direction! http://www.microsoft.com/ err somewhere on their crappy website. If you have Windows 98, I do believe DX is built into the operating system.

DS4QB does not support variable-bitrate MP3s. This is a limitation of bass.dll and nothing we at LSS screwed up =)

Because this requires Win32 to operate, long filenames are supported. Take advantage!

DS4QB.EXE constantly polls the clipboard. This means that clipboard services are not available while it is running. Take heed! Also, it does not restore the clipboard once it finishes. Clipboard restoration upon termination is something I've yet to add.

A final word before we get to the routines: although this was designed for Microsoft QuickBasic 4.5, there is absolutely no reason why this couldn't be used from ANY DOS-based language that has the capability to generate a software interrupt. I might do a C and PASCAL translation someday. Anyone wishing to do this first, please, feel free to do so.

ROUTINES:
I wrote these in order to return a value, however, none of them do since I botched up handshaking. Oh well.

FUNCTION InitDS4QB
Returns 0 if DS4QB is initialized, nonzero if not. THIS MUST BE USED or no sound services will work because this initializes the clipboard, and now also starts the slave module.

FUNCTION LoadModule (ModuleName AS STRING, Repeat AS INTEGER)
Loads a MOD, S3M, XM, IT, or MO3 module into memory. Set Repeat to a nonzero value for looping. Returns 0 if failed, nonzero otherwise. Although Bass.dll can actually load and play multiple modules at once, I limited this to one module. Multiple modules might be cool for music fading, but for now, DS4QB only supports one loaded module at a time, sorry. With alteration, it'll certainly handle more. I might implement this later.

FUNCTION RemoveModule
Removes the module from memory, optionally stops it if it's playing.

FUNCTION LoadStream (Filename AS STRING, Repeat AS INTEGER)
The most coveted thing in QB since the invention of the graphical library =) Loads the specified MP3 or WAV into the stream buffer. Set Repeat to nonzero for autorepeat of the stream.

FUNCTION RemoveStream
Removes the MP3 or WAV from the buffer and optionally stops it. Returns 0 if failed, nonzero otherwise.

FUNCTION LoadSample(SampleName AS STRING)
Back when this was supposed to load samples one-at-a-time...I just never changed anything =D this loads a script containing the filenames of the samples you want loaded into memory. See TESTWAVS.TXT for a demo on how this works. You can load up to 999 samples into memory at once.

FUNCTION RemoveSample
Removes all samples from memory. This, too, was originally written when this was supposed to be handled one-at-a-time.

FUNCTION PlayCD (Track AS INTEGER, Repeat AS INTEGER)
If CD audio is available, this plays the CD at the specified track. Set Repeat to 1 to make it repeat. If you don't tell it to repeat, it will go on to the next track once it's done playing. There is no command to stop a CD playing, and I haven't yet tested skipping around tracks, but it SHOULD work in theory...

SUB ShutdownDS4QB
Closes down the slave module and ends all playback instantly.

GLOBALS AND CONSTANTS:

False: This equals 0.
True: This is created with NOT False, so it should be -1.

WHO IS RESPONSIBLE FOR DS4QB:

-Jesus Christ: My Lord and Saviour. The reason I keep on codin'.
-Ian Luck: Wrote the Bass DLL. Excellent work dude.
-Adam Hoult: Wrote the VB API for Bass.dll. Niceness.
-Carl Gorringe: For writing WORKING clipboard routines. They work when mine went nuts.
-Ralf Brown: For his exhaustive efforts collecting data on PC interrupts. Damn man...I'm glad I'm not you =)
-Logic Lord: Made the first suggestions for this project (the clipboard usage). ALSO, showed me how to heavily reduce latency.
-QbProgger: Helped out time-wise by mentioning the exact interrupt to use =)
-Toshi Horie: A massive pillar of support in using the clipboard, and pointed me to a usable program when mine went awry.
-XlatB: Let me know that I'm psychotic for using a polling clipboard =)
-Wafn: First tester of some early prototypes.
-Lord Agnathian: For suggesting I control the slave's loading/unloading through the controller itself, instead of separately.
-leroy: For being the very first to suggest the clipboard idea, and for fixing DS4QB so it could start the slave properly.
-Everyone on #quickbasic who liked my idea: they kinda cheered me on as the production of this went on =)
-Nekrophidius: Me! Wrote the DS4QB controller and documentations.
